update to support descriptions with file links #8
Conversation
|
@pawamoy would be great if we can get this merged. Happy to make any additional changes |
There was a problem hiding this comment.
Thanks a lot @logan-markewich!
What I'd prefer is that we keep using a list, and support items being either a string or a dict (with a single key/value pair):
sections:
Usage documentation:
- file1.md
- file2.md: Description of file2This has a few benefits:
- it lets users add descriptions incrementally
- it makes the ordering explicit (in our case dicts would be loaded ordered from Python YAML, but that's not always the case for other languages in which the YAML data could be loaded)
WDYT?
|
Thats fair @pawamoy -- I can make that change |
|
@pawamoy ok, I think this is kind of what you were getting at? While the tests pass, I don't actually know how to give this an mkdocs.yml to test e2e 😅 But if you want to take it for a spin go for it! |
|
I tried to simplify the code: we now always expand the inputs into a dict of sections (key = section name) where values are dicts of files (key = relative file path, value = description). This way it's expanded once and for all and we avoid intermediate transformations or additional variable to store intermediate data. You could think: "why not reading dicts directly from the config file then" (since I made you go from dicts to lists), and the answer would be: the YAML syntax wouldn't allow you to have keys without values, so the list makes it a bit more elegant IMO. sections:
Some section:
page1.md: # not elegant
page2.md: descriptionsections:
Some section:
- page1.md # colon not needed, more elegant
- page2.md: description(also we maintain backward compatibility) I also reworked the tests. Let me know what you think 🙂 |
This PR adds new config options to provide a description with each page link
Which would generate something like
Added some unit tests, so I think this will work nicely? Open to changes!